Scenario #9032: A Global Admin Can Synchronize a New Group Subject

UseCase Synchronize Subject => SubjectSync: /sync-Team

The external Keycloak sync program synchronizes a single subject through the UUID-keyed idempotent PUT /api/rbac/subjects/{subjectUuid}. The UUID in the path is the same UUID as in Keycloak. Creating a new subject returns 201 Created, updating an existing subject’s name returns 200 OK. Only a global-admin may synchronize subjects (others are rejected with 403). Without an explicit organization, only realm-prefixed names are accepted (others are rejected with 400) and the organization is derived from the name prefix. With an explicit organization, USER names are free except that they must not start with /; GROUP names must start with / directly followed by the organization, because JWTs reference groups just by name and thus the organization must stay derivable from it.

Properties

Given

name	value
subjectUuid	238a0002-0000-0000-0000-000000000002
subjectName	/sync-Team
subjectType	GROUP

Synchronize the subject via HTTP PUT

HTTP PUT "/api/rbac/subjects/238a0002-0000-0000-0000-000000000002" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }` \
  <<EOF
{
  "name" : "/sync-Team",
  "type" : "GROUP"
}
EOF
=> status: 201 CREATED 238a0002-0000-0000-0000-000000000002

The stored subject carries the expected organization

HTTP GET "/api/rbac/subjects/238a0002-0000-0000-0000-000000000002" \
  -H "Authorization: Bearer $HSADMINNG_JWT_BEARER" \
  `# {` \
  `#   "sub" : "uuid<hsh-alex_superuser>"` \
  `# }`
=> status: 200 OK 
{
  "uuid" : "238a0002-0000-0000-0000-000000000002",
  "name" : "/sync-Team",
  "organization" : "sync",
  "type" : "GROUP"
}

---

generated on 2026-08-10 01:38:10 for branch